home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 4 / Apprentice-Release4.iso / Source Code / C / Frameworks / Extension Shell 1.4 / Extension Shell 1.4 (Source) / Extension Shell 1.4 Includes / ES.h < prev   
Text File  |  1995-11-03  |  8KB  |  276 lines
  1. /*    NAME:
  2.         ES.h
  3.  
  4.     WRITTEN BY:
  5.         Dair Grant
  6.                 
  7.     DESCRIPTION:
  8.         This file documents the interface between your code (the ES Handler,
  9.         any custom address table, and your installable routines) and
  10.         Extension Shell.
  11.  
  12.     ___________________________________________________________________________
  13. */
  14. #ifndef __EXTENSION_SHELL_1_4__
  15. #define __EXTENSION_SHELL_1_4__
  16. #pragma options align=mac68k
  17. //=============================================================================
  18. //        Include files                                                                     
  19. //-----------------------------------------------------------------------------
  20. #include <Retrace.h>
  21. #include <Shutdown.h>
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37. //=============================================================================
  38. //        Defines                                                                 
  39. //-----------------------------------------------------------------------------
  40. #define kMaxNumIcons            20                    // 1..20 icon index
  41. #define kMaxNumCodeResources    10                    // 1..10 code resource index
  42.  
  43. #define kESHandlerCodeType      'Code'                // Type of the ES Handler code
  44. #define kAddrsTableCodeType       'Code'                // Type of the Address Table code
  45. #define kESHandlerCodeID           5000                // ID of the ES Handler code
  46. #define kAddrsTableCodeID          5001                // ID of the Address Table code
  47.  
  48. #define kInitialiseParamBlock    0                    // Message for the ES Handler code resource
  49. #define kInitialiseAddrsTable    1                    // Message for the ES Handler code resource
  50. #define kHandleError            2                    // Message for the ES Handler code resource
  51.  
  52. #define kShiftKey                0x38                // Keycode for the shift key
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68. //=============================================================================
  69. //        Structures                                                                 
  70. //-----------------------------------------------------------------------------
  71. // Six types of code resources are supported right now. Defines to pick them out
  72. // of the union are defined here, with their structures.
  73. #define kTrapPatchType                1                        // A Trap Patch
  74. #define kGestaltSelectorType        2                        // A Gestalt Selector
  75. #define kShutdownTaskType            3                        // A Shutdown Task
  76. #define kVBLTaskType                4                        // A VBL Task
  77. #define kLowMemFilterType            5                        // A low-mem filter
  78. #define kCodeBlockType                6                        // A block of code
  79. #define kTimeManagerTaskType        7                        // A Time Manager Task
  80.  
  81.  
  82.  
  83.  
  84. // TrapPatch information. Trap Patches need to hold the word of the
  85. // trap to patch. Your ES Handler is responsible for ensuring that the
  86. // trap is implemented - if you're patching something really new, or
  87. // something that's implemented by an Extension, you need to test
  88. // for its presence using the IsTrapAvailable routine.
  89. //
  90. // If globalPatch is true, the patch is applied to all applications.
  91. // Otherwise, the patch is applied to the application named in
  92. // appName. (THIS FEATURE IS NOT IMPLEMENTED - THE INFORMATION IS
  93. // HERE AS A TEMPLATE FOR NOW)
  94. typedef struct {
  95.     short            trapWord;
  96.     Boolean            globalpatch;
  97.     Str31            appName;
  98. } ATrapPatch;
  99.  
  100.  
  101.  
  102. // Gestalt selectors may want to override existing selectors. Set
  103. // overwriteExistingSelector to true if you want your selector
  104. // to replace any existing selector (of type theSelector), and
  105. // false if you want to the existing selector to be left untouched.
  106. typedef struct {
  107.     OSType            theSelector;
  108.     Boolean            overwriteExistingSelector;
  109. } AGestaltSelector;
  110.  
  111.  
  112.  
  113. // Shutdown tasks can pass in some flags - defined in Shutdown.h
  114. typedef struct {
  115.     short            theFlags;
  116. } AShutdownTask;
  117.  
  118.  
  119.  
  120. // Information for a VBL task.
  121. typedef struct {
  122.     short            vblCount;
  123.     short            vblPhase;
  124. } AVBLTask;
  125.  
  126.  
  127.  
  128. // Information for a low-mem filter. We need to hold the address
  129. // of the filter to hook ourselves into.
  130. typedef struct {
  131.     long            theEntryPoint;
  132. } ALowMemFilter;
  133.  
  134.  
  135.  
  136. // Information for a block of code. We don't actually need anything,
  137. // but we can't compile it without having something in the structure.
  138. typedef struct {
  139.     long            refCon;
  140. } ACodeBlock;
  141.  
  142.  
  143.  
  144. // Information for a Time Manager task. We need to hold the time (in
  145. // milliseconds) before the task is first executed.
  146. typedef struct {
  147.     long            theDelay;
  148. } ATimeManagerTask;
  149.  
  150.  
  151.  
  152.  
  153. // Each installable 'thing' is specified via a CodeInfo structure. This holds
  154. // the resource type and id of the code resource (e.g. 'Code', 1000), as well
  155. // as codeType and theCodeThing fields, which specify the type of data in
  156. // theCodeThing and type-specific data respectively.
  157. //
  158. // theAddress is an internal Extension Shell field, used to hold the
  159. // address of the thing installed/the thing that was replaced by the
  160. // thing installed (the meaning differs, depending on the type of 'the thing'.
  161. //
  162. // theAddress is read only.
  163. typedef struct {
  164.     OSType            resType;                                    // Resource type of thing
  165.     short            resID;                                        // Resource ID of thing
  166.     short            codeType;                                    // Type of this thing
  167.     union            {
  168.                     ATrapPatch            theTrapPatch;
  169.                     AGestaltSelector    theGestaltSelector;
  170.                     AShutdownTask        theShutdownTask;
  171.                     AVBLTask            theVBLTask;
  172.                     ALowMemFilter        theLowMemFilter;
  173.                     ACodeBlock            theCodeBlock;
  174.                     ATimeManagerTask    theTimeManagerTask;
  175.                     } theCodeThing;                                // Specific details for this thing
  176.     Ptr                theAddress;                                    // USED BY EXTENSION SHELL
  177. } CodeInfo;
  178.  
  179.  
  180.  
  181.  
  182. // The ParamBlock. All communication between your code and Extension Shell is done
  183. // through a pointer to one of these structures. Relevent sections are grouped
  184. // together.
  185. typedef struct {
  186.     // Misc (Extension Shell <--> ES Handler)
  187.     //
  188.     //        systemVersion holds 7.0.0 as 0x0700, 7.5.2 as 0x0752, etc.
  189.     //        NotificationMsg allows you to install Notification Manager requests.
  190.     //        IsKeyMouseDown checks for a key/the mouse being pressed.
  191.     //        IsTrapAvailable checks for the presence of a trap.
  192.     //        IsPowerMac returns true/false as the Mac CPU is 68K/PPC.
  193.     //        IsTrapNative returns true/false as a given trap is fat.
  194.     long            systemVersion;
  195.     pascal void        (*NotificationMsg)(short errStrings, short theErr);
  196.     pascal Boolean    (*IsKeyMouseDown)(short keyCode, Boolean checkMouse);
  197.     pascal Boolean    (*IsTrapAvailable)(short trapWord);
  198.     pascal Boolean    (*IsPowerMac)(void);
  199.     pascal Boolean    (*IsTrapNative)(short trapWord);
  200.     
  201.     
  202.  
  203.     // Icons (Extension Shell <-- ES Handler)
  204.     //
  205.     //        numIcons contains the number of valid entries in theIcons, from 0..N.
  206.     //        animationDelay is the number of ticks to wait between showing icons.
  207.     //        theIcons is an array of the resource IDs of the icons to show.
  208.     short            numIcons;
  209.     short            animationDelay;
  210.     short            theIcons[kMaxNumIcons+1];
  211.     
  212.     
  213.     
  214.     // Address Table (Extension Shell <-- ES Handler)
  215.     //
  216.     //        installAddressTable indicates if your Extension wants an address table.
  217.     //        addressTableSelector indicates the selector for your address table.
  218.     Boolean            installAddressTable;
  219.     OSType            addressTableSelector;
  220.  
  221.  
  222.  
  223.     // Modules To Install (Extension Shell <-- ES Handler)
  224.     //
  225.     //        numCodeResources contains the number of valid entries in theCodeResources.
  226.     //        theCodeResources contains the information for each code resource to install.
  227.     int                numCodeResources;
  228.     CodeInfo        theCodeResources[kMaxNumCodeResources+1];
  229.  
  230.  
  231.  
  232.     // Error Handling (Extension Shell --> ES Handler)
  233.     //
  234.     //        errorIndex contains the entry in theCodeResources which could not be installed.
  235.     //        theErr contains the reason why theCodeResources[errorIndex] failed.
  236.     short            errorIndex;
  237.     OSErr            theErr;
  238.     
  239.     
  240.     
  241.     // Error Reporting (Extension Shell <-- ES Handler)
  242.     //
  243.     //        removeInstalledCode indicates if Extension Shell should try an uninstall.
  244.     //        beepNow indicates if Extension Shell should beep now.
  245.     //        postError indicates if Extension Shell should install a Notification Manager message.
  246.     //        errorStringsID contains the 'STR#' resource ID for a Notification Manager message.
  247.     //        errorStringsIndex contains the string index for a Notification Manager message.
  248.     Boolean            removeInstalledCode;
  249.     Boolean            beepNow;
  250.     Boolean            postError;
  251.     short            errorStringsID;
  252.     short            errorStringIndex;
  253. } ESParamBlock;
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269. //=============================================================================
  270. //        Routine descriptors                                                                 
  271. //-----------------------------------------------------------------------------
  272. typedef void (*ESHandlerProc)(short theMsg, ESParamBlock *theParamBlock);
  273.  
  274. #pragma options align=reset
  275. #endif
  276.